home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1990: Night of the Living Disc / Night of the Living Disc.hdv / Dev.CD.5 / Tools / Technical.Notes / GSOS / TN.GSOS.004 < prev    next >
Encoding:
Text File  |  1989-07-21  |  7.8 KB  |  137 lines  |  [04] ASCII Text (0x0000)
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. GS/OS
  8. #4:    A GS/OS State of Mind
  9.  
  10. Revised by:    Dave Lyons & Matt Deatherage                         July 1989
  11. Written by:    Matt Deatherage                                   January 1989
  12.  
  13. This Technical Note discusses GS/OS concepts and practices.
  14. Changes singe January 1989:  Updated for System Software 5.0.
  15. _____________________________________________________________________________
  16.  
  17. Although GS/OS bears many similarities to ProDOS, GS/OS is a much wider-
  18. reaching operating system, working not only with multiple file systems but 
  19. also with character devices.  Some things which work under ProDOS cause 
  20. problems under GS/OS, and application programmers need to be aware of the 
  21. differences, particularly those developing text-based programs.
  22.  
  23.  
  24. GS/OS Hints
  25.  
  26. Be aware of character devices.  A legal GS/OS pathname, perhaps entered 
  27. by a user in response to a prompt, could map to a character device, with 
  28. potentially disastrous results.  Error $58, Not a Block Device, can protect 
  29. you against this on many calls, including Create, but you must still take 
  30. precaution.  DInfo tells you if a device is a character device or block 
  31. device; bit seven of the characteristics word is set if the device is a block 
  32. device.
  33.  
  34. Don't preprocess pathnames.  A user input routine which prevents users 
  35. from entering pathnames that don't follow ProDOS syntax may help prevent 
  36. Illegal Pathname Syntax errors, but it also keeps users from creating files on 
  37. non-ProDOS disks with anything but ProDOS pathname syntax, and it could keep 
  38. them from accessing files on non-ProDOS disks which they created with another 
  39. GS/OS application.  Since the only FST which allowed you to write to a device 
  40. under System Software 4.0 was ProDOS, you didn't see this problem right away.  
  41. However, System Software 5.0 includes an AppleShare FST which, compared to 
  42. ProDOS, is fast and loose with pathnames.  "How about an anti-ProDOS name?" is 
  43. a legal AppleShare filename.  To allow compatibility with present and future 
  44. non-ProDOS FSTs, Apple suggests you pass user-entered pathnames directly to 
  45. GS/OS, with no application preprocessing.
  46.  
  47. Remember that under GS/OS both colons and slashes are valid separators, and 
  48. colons can only be separators.  In addition, all eight bits of each byte of a 
  49. pathname are significant.  Refer to GS/OS Reference, Volume 1 for more 
  50. information on GS/OS pathname syntax.  Using all eight bits of each byte may 
  51. be particularly difficult for text-based applications, which have no way to 
  52. force the standard Apple II character set to display characters such as sigma 
  53. or the copyright symbol; they can fiddle to get characters like the sterling 
  54. pound sign and an Apple.  Some programs may wish to adopt special 
  55. typographical conventions for these special characters while others may choose 
  56. not to create files with such characters in their names.  These programs could 
  57. present the user with a list of existing filenames (with some substitution for 
  58. the characters which are unavailable), while providing a method of choosing 
  59. one, to retrieve such files.  Any way around this problem for a text-based 
  60. program will be less than optimal.
  61.  
  62. Avoid the Text Tools and all slot dependencies.  Preliminary GS/OS 
  63. documentation points to a System Service call named DYN_SLOT_ARBITER.  This 
  64. mechanism, which is not fully implemented in System Software 5.0, eventually 
  65. will allow the operating system to use internal ports and external slots for 
  66. the same "slot" in the same session, instead of requiring the user to reboot 
  67. the system to safely change between ports and slots.  Applications which have 
  68. hard-coded slot dependencies (as the Text Tools unfortunately require) make 
  69. this transition very difficult, both for GS/OS and for the applications and 
  70. users.  We recommend that applications use the GS/OS loaded and generated 
  71. character device drivers for text output.  A DInfo call will tell you what 
  72. slot or port a driver controls, and whether or not it is a character device.
  73.  
  74. Avoid other file system dependencies.  Many of the things ProDOS 
  75. programmers are used to as facts of life just are not true any longer.  For 
  76. example, filenames don't have to be 15 characters or less under GS/OS.  When 
  77. making class one calls, GS/OS will tell you if you don't have enough room for 
  78. the pathname by returning a Buffer Too Small error ($4F).  Avoiding file 
  79. system dependencies means handling this error intelligently:  if you receive 
  80. it, allocate more space for the buffer and try the call again.  GS/OS will 
  81. tell you how much space is needed.  If you absolutely must hard code 
  82. pathnames, such as volume names, be sure to use the colon as the separator, 
  83. because if you do not, filenames with slashes will cause problems.  Similarly, 
  84. don't assume any of the following:
  85.  
  86.   o  There can only be 51 files in the volume directory
  87.   o  All devices are named ".Dn," where n is the device number
  88.   o  All blocks are 512 bytes long
  89.   o  All devices are block devices
  90.   o  Any other ProDOS-specific characteristics
  91.  
  92. Don't hog all of the memory.  While this is never a good idea on the 
  93. IIGS, it's even worse under GS/OS.  To process things like pathnames, GS/OS 
  94. allocates memory through the Memory Manager.  If you've allocated all of 
  95. available memory (i.e., for a disk copy procedure), GS/OS will be forced to 
  96. return an Out of Memory error ($54).  If the condition is so severe that GS/OS 
  97. can no longer function, it will return a fatal GS/OS error with an ID = 2, and 
  98. the user will be asked to restart the system.
  99.  
  100. (A common cause of fatal GS/OS error 2 during development is using a length 
  101. byte instead of a length word on a class one string.  Doing so almost always 
  102. causes the first word to be greater than 8K, which is the maximum length of 
  103. pathnames under GS/OS.  GS/OS then dies for your enjoyment, as it is unable to 
  104. allocate the memory for the pathname because it's too big, even if more than 
  105. 8K is available.)
  106.  
  107. Hard code as little as possible.  Even seemingly static things like 
  108. device names should not be hard coded, since a new loaded driver could change 
  109. the name of the same device at any time.  Also, it may be possible in the 
  110. future for users to rename devices.
  111.  
  112. Only ask for the access you need.  If you're just going to read a file, 
  113. make a call to Open the file with read permission only.  In file systems where 
  114. access privileges mean more than they traditionally have in ProDOS (where 
  115. things are usually "Locked" or "Unlocked"), this could save some trouble.  For 
  116. example, AppleShare allows the same file to be opened multiple times as long 
  117. as each open is with read-only access.  If your program is only going to read 
  118. a file, opening it with read and write access needlessly denies others on the 
  119. server access to the file.
  120.  
  121. Copy all GS/OS information with files.  Applications that copy files 
  122. need to do more than copy the data fork of the file.  If the file is extended, 
  123. the resource fork of the file should be copied as well.  In addition, when 
  124. requested, each FST returns an option_list that contains information specific 
  125. to the host file system that GS/OS does not use (i.e., AppleShare's 
  126. option_list includes Finder information and access privileges).  Calls to 
  127. GetFileInfo and Open can return the option_list, while a call to SetFileInfo 
  128. can set it.  An FST will not set parameters in the option_list which should 
  129. not be altered (just as SetFileInfo skips the EOF fields in GetFileInfo 
  130. records).  To ensure that the duplicate has as much host file system 
  131. information from the original as can reasonably be transferred, always copy 
  132. the option_list.
  133.  
  134.  
  135. Further Reference
  136. _____________________________________________________________________________
  137.     o    GS/OS Reference, Volumes 1 and 2